fix(types): accept an explicit undefined wherever a consumer writes an optional member - #418

Problem

React Native declares its own optional props as ?: T | undefined, while the props this package adds are bare ?: string. Under exactOptionalPropertyTypes the two differ, so this fails to compile:

<View className={condition ? "p-4" : undefined} />

error TS2769: No overload matches this call.
  Overload 1 of 2, '(props: ViewProps): View', gave the following error.
    Type '{ className: string | undefined; }' is not assignable to type 'Readonly<ViewProps>' with 'exactOptionalPropertyTypes: true'. Consider adding 'undefined' to the types of the target's properties.

styled() has the same bare members: the className its unmapped overload adds, passThrough, and a mapping's nativeStyleMapping and its entries; so do the options a consumer writes for the compiler, Metro, the jest helper and useNativeCss.

A nativeStyleMapping entry left undefined is also a runtime error: mappingToConfig keeps it, and the native style mapping calls path.split(".") on it:

const StyledView = styled(View, {
  className: {
    target: "style",
    nativeStyleMapping: { color: "accessibilityLabel", backgroundColor: undefined },
  },
});

// .subject { color: blue; background-color: red; }
// Rendering throws "Cannot read properties of undefined (reading 'split')",
// and the render React recovers with has no backgroundColor.
<StyledView className="subject" />;

Solution

• Every optional member a consumer writes takes | undefined: the props types.d.ts adds; the props styled() adds, passThrough, nativeStyleMapping and its entries in runtime.types.ts; CompilerOptions, Metro's options, the jest helper's debug and useNativeCss's Config; and the Effect that get() takes on the observables StyleCollection exposes. Without the flag the types are unchanged.
• CompilerOptions.logger is ((message: string) => void) | Debugger | undefined, where (message: string) => void | Debugger made Debugger the function's return type.
• mappingToConfig drops a nativeStyleMapping entry left undefined.

Tests

• src/__tests__/native/styled.test.ios.tsx: a mapping entry set to undefined maps nothing, and the entry beside it still maps. On main its render throws, and yarn typecheck rejects its undefined entry.
• src/__tests__/types/optional-members.test.ts builds a program with exactOptionalPropertyTypes on and walks what a consumer writes: the props types.d.ts adds, runtime.types.ts, and what each entry point of package.json's exports takes. It fails on any optional member that rejects undefined, so a member added later is held to it too; on main it names the 42 places this PR widens.

Verification

yarn lint · yarn typecheck · yarn test 1418 passed · yarn build and node --test node/__tests__/*.mjs · yarn example expo export --platform web · commitlint: all green on this head on Ubuntu, with Node 26.12.1 (.nvmrc pins 22.18.0), and the iOS dev build on macOS 27.2 with Xcode 27.2, where ci.yml pins 26.6.

The className example above and the mapping snippet, each on main and on this branch, against the sources and against the built package, are in this comment.

In an Expo app, expo/types declares className on ViewProps, TextProps and other React Native props without | undefined, and expo-env.d.ts loads it before this package's declarations, so there the className example keeps failing until Expo's declarations take | undefined too, which expo/expo#43508 tracks.

Merge order

• fix(native): answer :dir() per element, and compile every spelling of it #459 adds dir to ViewProps and TextProps in types.d.ts; whichever lands second gives it | undefined, which optional-members.test.ts checks.
• fix: avoid walking ref props in styled mappings #344 rewrites the nativeStyleMapping declaration in src/runtime.types.ts, and fix(native): give a target:false config its own scratch space, and never map onto the cached props #435 makes Config's members read-only in src/native/react/useNativeCss.ts; whichever lands second keeps both changes, | undefined included.